home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / mig / Mig.man < prev    next >
Text File  |  1990-02-28  |  10KB  |  219 lines
  1. \fB'\" $Header: /sprite/src/lib/c/mig/RCS/Mig.man,v 1.2 90/02/28 11:00:30 douglis Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Mig lib
  4. .BS
  5. .SH NAME
  6. Mig \- obtain or update information in the migration information database.
  7. .SH SYNOPSIS
  8. .nf
  9. \fB#include    <mig.h>\fR
  10.  
  11. Mig_Info *
  12. \fBMig_GetInfo\fR(\fIspriteID\fP)
  13.  
  14. int
  15. \fBMig_GetAllInfo\fR(\fIinfoArray, numHosts\fP)
  16.  
  17. int
  18. \fBMig_RequestIdleHosts\fR(\fInumHosts, priority, flags, callBackPtr, hostArray\fP)
  19.  
  20. int
  21. \fBMig_ConfirmIdle\fR(\fIspriteID\fP)
  22.  
  23. int
  24. \fBMig_ReturnHosts\fR(\fInumHosts, hostArray\fP)
  25.  
  26. int
  27. \fBMig_DeleteHost\fR(\fIspriteID\fP)
  28.  
  29. int
  30. \fBMig_Evict\fR()
  31.  
  32. char *
  33. \fBMig_GetPdevName\fR(\fIglobal\fP)
  34.  
  35. int
  36. \fBMig_GetIdleNode\fR()
  37.  
  38. int
  39. \fBMig_Done\fR(\fIspriteID\fP)
  40.  
  41. .SH ARGUMENTS
  42. .AS void (*callBackPtr)() in
  43. .AP int spriteID in
  44. The Sprite ID of the host for which information should be obtained or updated.
  45. .AP Mig_Info infoArray[] out
  46. A buffer to hold Mig_Info entries returned by the Mig_GetAllInfo routine.
  47. The size of the buffer is specified in the \fInumHosts\fP variable.
  48. .AP int numHosts in
  49. The number of Mig_Info structures contained in \fIinfoArray\fP.
  50. Or, the number of hosts requested from \fBMig_RequestIdleHosts\fR and
  51. the number of hosts returned to \fBMig_ReturnIdle\fR.  
  52. .AP int priority in
  53. Priority of processes to be migrated to idle hosts (see below).  
  54. .AP int flags in
  55. Flags to be passed to the migration daemon (see below).
  56. .AP void (*callBackPtr)() in
  57. Routine to call if not enough hosts are available and
  58. additional hosts are later available.
  59. .AP int global in
  60. Whether to return the name of the pseudo-device for the global daemon
  61. or host-specific daemon.
  62. .BE
  63. .SH DESCRIPTION
  64. These functions are used to obtain (or update) information about hosts on the 
  65. Sprite network.  There are routines to get information about specific
  66. hosts or all the hosts on the network, to select one or more idle hosts for
  67. process migration, to cause processes to be evicted, or to remove
  68. hosts that are down from the list of hosts on the network.  
  69. .PP
  70. Most of the routines interact with a single network-wide daemon, known
  71. as the \fIglobal daemon\fP, to obtain information or make requests.
  72. This \fBmigd\fP daemon maintains state about all hosts on the network,
  73. including their load averages, idle time, and availability for use
  74. with migration.   In addition, each host runs a per-host instance of
  75. \fBmigd\fR that samples load and evicts processes automatically when
  76. it detects user input.    The \fBMig\fR library opens a pseudo-device
  77. to communicate with the appropriate \fBmigd\fR daemon (global or
  78. local) depending on the operation being performed.  Also, if an error
  79. occurs communicating with a daemon, the \fBMig\fR library
  80. reestablishes communication.
  81. .SH GETTING HOST INFORMATION
  82. The migration daemon, and the migration library, communicate using a
  83. structure defined in mig.h, known  as a Mig_Info structure.  
  84. Each host has a Mig_Info structure associated with it.  The structure
  85. has another structure included within it; the Mig_LoadVector is
  86. updated periodically by the \fBmigd\fR process on each host.  The rest
  87. of the data in a Mig_Info structure are established at boot-time or are
  88. maintained by the global daemon.  
  89. .PP
  90. The global daemon maintains the state of each host.  The states are
  91. defined in mig.h.  The most important ones are MIG_HOST_DOWN, which
  92. indicates that the rest of the Mig_Info structure is irrelevant with
  93. the exception of loadVec.timestamp, which indicates when the host was
  94. last up; MIG_HOST_IDLE, indicating that a host is available for
  95. migration; MIG_HOST_FULL, which shows that the host is accepting
  96. migration but already has foreign processes; and MIG_HOST_ACTIVE,
  97. which indicates that a user is actively using the machine or the
  98. machine's load is too high to permit foreign processes.
  99. .PP
  100. The load vector includes weighted
  101. average CPU utilizations and ready-queue lengths, as well as the time since
  102. input was last received from users directly logged into the machine.  (Remote
  103. logins do not affect idle time.)  Finally, each entry indicates whether the
  104. host is willing to accept processes for migration.   \fBmigd\fR 
  105. is responsible for determining whether migration
  106. is allowed, based on factors such as load and idle time.  
  107. .PP
  108. \fBMig_GetInfo()\fR returns a pointer to a Mig_Info structure based on the sprite 
  109. ID of a host. 
  110. The structure is statically allocated by Mig_GetInfo, and the contents of
  111. the structure may change on subsequent calls to Mig_GetInfo.  On
  112. error, a NULL pointer is returned.
  113. .PP
  114. \fBMig_GetAllInfo()\fR returns an array of Mig_Info structures.  The array
  115. must be allocated by the caller, and a pointer to the array must be
  116. passed to \fBMig_GetAllInfo()\fR, along with the size of the array.  The
  117. number of entries filled in \fiinfoArray\fP is returned.  On error, -1
  118. is returned and the global variable \fIerrno\fP indicates the nature
  119. of the error.  
  120. .PP
  121. .SH GETTING IDLE HOSTS
  122. The global daemon maintains open connections to both per-host
  123. \fBmigd\fR daemons and user processes that are using idle hosts.  User
  124. processes can request idle hosts using any of three priorities,
  125. MIG_LOW_PRIORITY, MIG_NORMAL_PRIORITY, and MIG_HIGH_PRIORITY.
  126. MIG_LOW_PRIORITY is for long-running background processes that are to
  127. be run at low execution priority.  MIG_NORMAL_PRIORITY is for normal,
  128. relatively short-lived processes such as compiles.  MIG_HIGH_PRIORITY
  129. is not yet in general use.  Hosts with foreign processes of one
  130. priority can still accept more processes of higher priority, so
  131. simulations won't interfere with compiles.
  132. .PP
  133. Processes communicate with the global daemon using ioctls, and
  134. normally, those streams are
  135. not readable. 
  136. The global daemon makes the streams readable to indicate that a change
  137. of state has occurred.  The \fBMig\fR library 
  138. relies on \fBselect()\fR to determine whether the global daemon has
  139. information about changes.  In this way, communication with the daemon
  140. may be minimized, since applications can check for new idle hosts or
  141. evictions on hosts they were using, without ever communicating with
  142. the daemon. 
  143. .PP
  144. \fBMig_RequestIdleHosts()\fR requests one or more idle hosts from the
  145. global daemon.   The number of hosts available is returned.  The
  146. \fIpriority\fR must be specified as one of the priorities listed
  147. above.  The \fIflags\fR may be 0 or MIG_PROC_AGENT, which indicates
  148. that the process requesting the host will not indicate when the
  149. processes being migrated are through, and instead the hosts to which
  150. the processes are migrated should monitor foreign processes and note
  151. when they are no longer in use for migration.   The \fIcallBackPtr\fR
  152. may be NULL or a pointer to a void function that will be invoked when
  153. additional hosts are available, if an insufficient number of hosts are
  154. granted by the global daemon at the time of the call.  \fIhostArray\fR
  155. points to an area that can hold up to \fInumHosts\fR host identifiers.
  156. .PP
  157. \fBMig_ConfirmIdle(\fIhostID\fB)\fR verifies that a host is still
  158. available.  If 
  159. the host is available, 
  160. \fBMig_ConfirmIdle()\fR returns 1 (TRUE).  If the host is not
  161. available, or an error occurs, \fBMig_ConfirmIdle()\fR returns 0 (FALSE).
  162. In this case, the caller may request a new idle host.  
  163. .PP
  164. \fBMig_ReturnHosts()\fR returns one or more idle hosts to the pool.
  165. Note: all hosts requested by a process are returned to the pool of
  166. idle hosts when the stream that connects the process to the global
  167. daemon is closed (i.e., when the process and all its children that may
  168. have inherited the stream have exited).  
  169. .SH BACKWARD COMPATIBILITY
  170. Two functions are implemented to provide a backward compatible
  171. interface for users of the original \fBMig\fR library.  
  172. .PP
  173. \fBMig_GetIdleNode()\fR returns the number of an idle node.  If no host is
  174. available, then 0 is returned.  On error, -1
  175. is returned and the global variable \fIerrno\fP indicates the nature
  176. of the error.  
  177. .PP
  178. \fBMig_Done()\fR returns a single host to the pool of idle hosts.
  179. .SH MISCELLANEOUS
  180. .PP
  181. \fBMig_DeleteHost()\fR removes a host from the database maintained by
  182. the global daemon.  The host must be down at the time.  This may be used
  183. if a host is removed from the network or renamed.
  184. .PP
  185. \fBMig_Evict()\fR performs an \fIioctl\fP to the local \fBmigd\fR
  186. daemon, requesting that it evict any foreign processes.  Normally,
  187. eviction is automatic when a host becomes active after being idle.
  188. This routine provides the \fBloadavg\fP program with the ability to
  189. request evictions at other times (for example, from a remote login).
  190. .PP
  191. \fBMig_GetPdevName()\fR is used by the migration library and by
  192. \fBmigd\fR to get the name of pseudo-devices to open.  It would not
  193. normally be used by other programs.
  194. .SH DIAGNOSTICS
  195. Most \fBMig\fR routines
  196. return zero if 
  197. all went well.  Otherwise 
  198. they return -1 and the \fIerrno\fR variable contains additional information
  199. about what error occurred.  \fBMig_GetIdleNode()\fR  and
  200. \fBMig_RequestIdleHosts()\fR   similarly return -1 on 
  201. error, but they return 0 if no idle host is available.  \fBMig_GetInfo()\fR
  202. returns
  203. NULL on error. 
  204. .SH FILES
  205. .IP /sprite/admin/migd.log
  206. The global migration daemon error log.  
  207. .IP /hosts/$HOST/migd.log
  208. The error log used by host $HOST.
  209. .IP /sprite/admin/migInfo.pdev
  210. The pseudo-device used to communicate with the global daemon.
  211. .IP /hosts/$HOST/migInfo.pdev
  212. The pseudo-device used to communicate with the local daemon.
  213. .IP /sprite/admin/migd.check
  214. The file used to store the most recent information about host uptimes.
  215. .SH KEYWORDS
  216. migration, load average, idle time, pseudo-device, eviction
  217. .SH SEE ALSO
  218. migd, loadavg, pmake, pdev
  219.